XML-RPC-Alarmsteuerung

Die XML-RPC-Alarmsteuerung erlaubt Drittsystemen, eine in Notruf & Alarmierung hinterlegte Alarmierung per HTTP-Aufruf zu starten und wieder zu beenden. Typische Aufrufer sind Brandmeldeanlagen, Gebäudeleittechnik, Rufanlagen (etwa in Pflegeeinrichtungen) und Panikschalter — Systeme, die im Ereignisfall genau einen vorbereiteten HTTP-POST absetzen. Beide Befehle sind bewusst parameterlos: Das auslösende System muss weder SIP sprechen noch Nutzdaten zusammenbauen.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Keine Authentifizierung — netzseitige Einschränkung ist Voraussetzung

Die Schnittstelle ist standardmäßig deaktiviert. Im aktivierten Zustand verlangen die beiden Befehle keine Anmeldung: Jedes System, das den Endpunkt https://<host>/xml-rpc erreichen kann, kann einen Alarm auslösen oder beenden. Aktivieren Sie die Schnittstelle nur, wenn der Zugriff auf die STARFACE bereits netzseitig eingeschränkt ist (Firewall, Netzsegmentierung, IP-Filter). Details unter Sicherheit.

Grundlagen

Typ: XML-RPC über HTTP-POST
Endpunkt: https://<host>/xml-rpc — z. B. https://pbx.example.de/xml-rpc
Methodenname: <Instanzname>.<Befehl> — der Name Ihrer Modulkonfiguration, gefolgt vom Befehl, z. B. Alarmierung.rpcStartEmergencyCall
Parameter: keine; das <params>-Element darf im Request vollständig entfallen
Content-Type (Request): application/xml
Antwort: HTTP-Status 200 mit XML-RPC-methodResponse; die Erfolgsantwort enthält ein leeres struct und keine Nutzdaten
Authentifizierung: keine (bewusst; siehe Sicherheit)
Voraussetzungen: aktivierte Schnittstelle, aktive Modulkonfiguration, gültige Modullizenz (die Lizenz wird beim Auslösen eines Alarms geprüft)

Aktivierung

Sie aktivieren die Schnittstelle in der Moduloberfläche im Tab im Abschnitt Auslöser für Alarme, Block XML-RPC Schnittstelle:

Setzen Sie das Kontrollkästchen Aktiv. Erst dadurch registriert das Modul die beiden Methoden an der STARFACE-XML-RPC-Schnittstelle — im deaktivierten Zustand existieren sie nicht.
Wählen Sie unter Alarmkonfiguration, welche Alarmkonfiguration rpcStartEmergencyCall auslöst. Je Modulkonfiguration ist genau ein Ziel hinterlegbar.

Der Methodenname enthält den Namen der Modulkonfiguration („Instanzname"). Nach dem Umbenennen der Modulkonfiguration gelten sofort die neuen Methodennamen; Aufrufe unter dem alten Namen schlagen fehl. Enthält der Name XML-Sonderzeichen (etwa &), müssen diese im rohen XML-Body maskiert werden (&) — für per API angesprochene Modulkonfigurationen empfiehlt sich daher ein Name ohne Sonderzeichen.

Postman-Sammlung

Die Moduloberfläche zeigt im Block XML-RPC Schnittstelle die fertigen Request-Bodys Ihrer Installation an (Link HTTP-POST-Request) und erzeugt daraus auf Knopfdruck eine Postman-Sammlung (Collection-Format v2.1) mit beiden Aufrufen — Endpunkt, Content-Type-Header und Methodennamen sind bereits ausgefüllt.

Befehle

`rpcStartEmergencyCall`

Löst die im Modul unter Alarmkonfiguration hinterlegte Alarmkonfiguration aus. Das Modul ruft die über den Endgerätefilter der Konfiguration bestimmten Telefone an, nimmt sie — soweit vom Endgerät unterstützt — automatisch ab, zeigt den konfigurierten Displaytext an und spielt die hinterlegte Ansage wiederholt ab. Abhängig von der Alarmkonfiguration werden laufende Gespräche der Zielgeräte zuvor getrennt.

Die Antwort bestätigt die Annahme des Aufrufs, nicht das Ergebnis der Alarmierung:

Situation	Verhalten
Schnittstelle aktiv, Ziel-Alarmkonfiguration vorhanden	Alarm wird ausgelöst
Keine Alarmkonfiguration ausgewählt oder Konfiguration zwischenzeitlich gelöscht	Kein Alarm; Antwort bleibt Erfolg, Ursache steht nur im Modul-Log
Modullizenz ungültig	Kein Alarm; Antwort bleibt Erfolg, Ursache steht nur im Modul-Log
Endgerätefilter liefert keine Telefone	Kein Alarm; Antwort bleibt Erfolg, Ursache steht nur im Modul-Log
Alarm läuft bereits	Keine Prüfung — die Alarmkonfiguration wird erneut ausgeführt. Beenden Sie einen laufenden Alarm ggf. zuerst per `rpcStopEmergencyCall`

Beispiel für eine Modulkonfiguration mit dem Namen „Alarmierung":

curl
Python

curl -X POST 'https://pbx.example.de/xml-rpc' \
  -H 'Content-Type: application/xml' \
  --data '<?xml version="1.0"?>
<methodCall>
    <methodName>Alarmierung.rpcStartEmergencyCall</methodName>
</methodCall>'

import xmlrpc.client

INSTANZNAME = 'Alarmierung'  # Name der Modulkonfiguration

pbx = xmlrpc.client.ServerProxy('https://pbx.example.de/xml-rpc')
getattr(pbx, INSTANZNAME + '.rpcStartEmergencyCall')()

Da der Methodenname den Namen der Modulkonfiguration enthält (häufig mit Leerzeichen), erfolgt der Aufruf in Python über getattr(...) statt über die Punktnotation.

Antwort 200 OK (zur Lesbarkeit formatiert):

<?xml version="1.0"?>
<methodResponse>
    <params>
        <param>
            <value><struct></struct></value>
        </param>
    </params>
</methodResponse>

`rpcStopEmergencyCall`

Beendet den laufenden Alarm der Modulkonfiguration — unabhängig davon, wodurch er ausgelöst wurde (XML-RPC, Anruf-Auslöser, Notruferkennung oder manuell in der Moduloberfläche). Alle Alarmverbindungen der Alarmkonferenz werden getrennt.

Der Befehl ist idempotent: Läuft kein Alarm, bleibt der Aufruf wirkungslos und wird dennoch mit Erfolg beantwortet.

curl
Python

curl -X POST 'https://pbx.example.de/xml-rpc' \
  -H 'Content-Type: application/xml' \
  --data '<?xml version="1.0"?>
<methodCall>
    <methodName>Alarmierung.rpcStopEmergencyCall</methodName>
</methodCall>'

import xmlrpc.client

INSTANZNAME = 'Alarmierung'  # Name der Modulkonfiguration

pbx = xmlrpc.client.ServerProxy('https://pbx.example.de/xml-rpc')
getattr(pbx, INSTANZNAME + '.rpcStopEmergencyCall')()

Die Antwort entspricht der von rpcStartEmergencyCall (leeres struct).

Anwendungsbeispiel

Ein Pflegeheim betreibt Notruftaster über eine eigene Rufanlage. Löst ein Taster aus, sendet die Rufanlage den hinterlegten HTTP-POST mit rpcStartEmergencyCall an die STARFACE — Sekunden später klingeln die DECT-Geräte des Pflegeteams mit Ansage und Displaytext, ohne dass die Rufanlage SIP sprechen muss.

Sicherheit

Die Schnittstelle ist standardmäßig deaktiviert. Solange das Kontrollkästchen Aktiv nicht gesetzt ist, sind die beiden Methoden an der STARFACE nicht registriert und jeder Aufruf schlägt fehl.
Im aktiven Zustand verlangen die Befehle bewusst keine Anmeldung. Jedes System mit Netzwerkzugriff auf den Endpunkt https://<host>/xml-rpc kann Alarme auslösen und beenden.
Netzseitige Einschränkung ist deshalb Voraussetzung für den Betrieb: Beschränken Sie den Zugriff auf die Web-Schnittstelle der Anlage per Firewall, Netzsegmentierung oder IP-Filter auf die auslösenden Systeme. Aktivieren Sie die Schnittstelle nicht, wenn der Endpunkt aus dem Internet erreichbar ist.
Der Name der Modulkonfiguration im Methodennamen ist kein Schutzmechanismus.
Deaktivieren Sie die Schnittstelle, wenn sie nicht benötigt wird. Beim Deaktivieren der Modulkonfiguration werden die Methoden ebenfalls entfernt und ein laufender Alarm beendet.

Fehlerbehandlung

Die STARFACE beantwortet auch Fehler mit HTTP-Status 200; der Fehler steht als XML-RPC-<fault> im Antwortkörper. Werten Sie daher den Antwortkörper aus, nicht den HTTP-Status.

Situation	Antwort
Schnittstelle deaktiviert, Modulkonfiguration inaktiv oder Methodenname falsch (z. B. nach Umbenennen der Modulkonfiguration)	`<fault>` mit `faultCode` `2` und `faultString` „No processor found for the identifier `<Methodenname>`"
Unerwarteter Fehler bei der Verarbeitung	`<fault>` mit `faultCode` `7` und `faultString` „An unexpected error has occurred in the code of the RPC server."
Fachliche Nichtausführung (fehlende Lizenz, kein Ziel ausgewählt, keine Endgeräte)	Kein Fehler — Erfolgsantwort mit leerem `struct`; die Ursache protokolliert das Modul im Modul-Log

Beispiel einer Fehlerantwort bei deaktivierter Schnittstelle (zur Lesbarkeit formatiert):

<?xml version="1.0"?>
<methodResponse>
    <fault>
        <value>
            <struct>
                <member>
                    <name>faultCode</name>
                    <value><int>2</int></value>
                </member>
                <member>
                    <name>faultString</name>
                    <value><string>No processor found for the identifier Alarmierung.rpcStartEmergencyCall</string></value>
                </member>
            </struct>
        </value>
    </fault>
</methodResponse>

Versionierung & Kompatibilität

Die Schnittstelle ist nicht explizit versioniert (kein Versionsbestandteil im Methodennamen). Die beiden Befehlsnamen und die parameterlose Aufrufform bilden den stabilen Vertrag der Schnittstelle; Änderungen und Erweiterungen dokumentieren die Release Notes der jeweiligen Modulversion. Zu beachten:

Der Methodenname ist an den Namen der Modulkonfiguration gebunden. Das Umbenennen der Modulkonfiguration ändert die Methodennamen und wirkt für angebundene Drittsysteme wie ein Breaking Change — passen Sie hinterlegte Aufrufe unmittelbar an.
Die Erfolgsantwort ist ein leeres struct ohne Nutzdaten. Verlassen Sie sich nicht auf Felder, die dort heute nicht vorhanden sind.

Grundlagen​

Aktivierung​

Postman-Sammlung​

Befehle​

rpcStartEmergencyCall​

rpcStopEmergencyCall​

Sicherheit​

Fehlerbehandlung​

Versionierung & Kompatibilität​